Upravljalniki poti v Next.js: Celovit vodnik za ustvarjanje API končnih točk

Next.js je s svojimi zmogljivimi funkcijami, kot so strežniško upodabljanje, generiranje statičnih strani in zdaj upravljalniki poti (Route Handlers), revolucioniral način izdelave spletnih aplikacij. Upravljalniki poti zagotavljajo prilagodljiv in učinkovit način za ustvarjanje API končnih točk neposredno v vaši aplikaciji Next.js. Ta vodnik raziskuje koncept upravljalnikov poti, njihove prednosti in kako jih učinkovito uporabiti za izgradnjo robustnih API-jev.

Kaj so upravljalniki poti (Route Handlers) v Next.js?

Upravljalniki poti so funkcije, definirane v mapi app projekta Next.js, ki obravnavajo dohodne HTTP zahteve. V nasprotju s starejšim pristopom pages/api (ki uporablja API poti), upravljalniki poti ponujajo bolj poenostavljen in prilagodljiv način za definiranje API končnih točk poleg vaših React komponent. V bistvu so to brezstrežniške funkcije, ki se izvajajo na robu omrežja (edge) ali v vašem izbranem strežniškem okolju.

Predstavljajte si upravljalnike poti kot backend logiko vaše aplikacije Next.js, odgovorno za obdelavo zahtev, interakcijo z bazami podatkov in vračanje odgovorov.

Prednosti uporabe upravljalnikov poti

• Kolokacija: Upravljalniki poti se nahajajo neposredno ob vaših React komponentah v mapi app, kar spodbuja boljšo organizacijo in lažje vzdrževanje kode.
• Podpora za TypeScript: Vgrajena podpora za TypeScript zagotavlja varnost tipov in izboljšano razvijalsko izkušnjo.
• Integracija vmesne programske opreme (Middleware): Enostavna integracija vmesne programske opreme za naloge, kot so avtentikacija, avtorizacija in validacija zahtev.
• Podpora za pretakanje (Streaming): Upravljalniki poti lahko pretakajo podatke, kar vam omogoča postopno pošiljanje odgovorov, kar je koristno pri velikih naborih podatkov ali dolgotrajnih procesih.
• Robne funkcije (Edge Functions): Uvedite upravljalnike poti kot robne funkcije za nizko-latentne odgovore bližje vašim uporabnikom, s čimer izkoristite globalna omrežja za dostavo vsebin (CDN).
• Poenostavljeno načrtovanje API-jev: Upravljalniki poti zagotavljajo čist in intuitiven API za obravnavo zahtev in odgovorov.
• Integracija s strežniškimi dejanji (Server Actions): Tesna integracija s strežniškimi dejanji omogoča nemoteno komunikacijo med vašimi odjemalskimi komponentami in strežniško logiko.

Nastavitev vašega Next.js projekta

Preden se poglobite v upravljalnike poti, se prepričajte, da imate nastavljen Next.js projekt z mapo app. Če začenjate nov projekt, uporabite naslednji ukaz:

            npx create-next-app@latest my-nextjs-app
            

              
                Copy
              
            
          

Med postopkom namestitve izberite mapo app, da omogočite nov sistem usmerjanja.

Ustvarjanje vašega prvega upravljalnika poti

Ustvarimo preprosto API končno točko, ki vrača odgovor v formatu JSON. V mapi app ustvarite novo mapo, na primer /app/api/hello. V tej mapi ustvarite datoteko z imenom route.ts (ali route.js, če ne uporabljate TypeScripta).

Tukaj je koda za vaš prvi upravljalnik poti:

            // app/api/hello/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 return NextResponse.json({ message: 'Hello from Next.js Route Handlers!' });
}

            

              
                Copy
              
            
          

Razlaga:

• import { NextResponse } from 'next/server';: Uvozi objekt NextResponse, ki se uporablja za sestavljanje API odgovorov.
• export async function GET(request: Request) { ... }: Definira asinhrono funkcijo, ki obravnava GET zahteve na končno točko /api/hello. Parameter request omogoča dostop do dohodnega objekta zahteve.
• return NextResponse.json({ message: 'Hello from Next.js Route Handlers!' });: Ustvari JSON odgovor s sporočilom in ga vrne z uporabo NextResponse.json().

Zdaj lahko do te končne točke dostopate z obiskom /api/hello v vašem brskalniku ali z uporabo orodja, kot sta curl ali Postman.

Obravnavanje različnih HTTP metod

Upravljalniki poti podpirajo različne HTTP metode, kot so GET, POST, PUT, DELETE, PATCH in OPTIONS. Za vsako metodo lahko definirate ločene funkcije znotraj iste datoteke route.ts.

            // app/api/users/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 // Logic to retrieve all users from the database
 const users = [{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]; // Example data
 return NextResponse.json(users);
}

export async function POST(request: Request) {
 const data = await request.json(); // Parse the request body as JSON
 // Logic to create a new user in the database using 'data'
 const newUser = { id: 3, name: data.name, email: data.email }; // Example
 return NextResponse.json(newUser, { status: 201 }); // Return the new user with a 201 Created status code
}

            

              
                Copy
              
            
          

Razlaga:

• Funkcija GET pridobi seznam uporabnikov (tukaj simulirano) in jih vrne kot JSON odgovor.
• Funkcija POST razčleni telo zahteve kot JSON, ustvari novega uporabnika (simulirano) in vrne novega uporabnika s statusno kodo 201 Created.

Dostopanje do podatkov zahteve

Objekt request omogoča dostop do različnih informacij o dohodni zahtevi, vključno z glavami, poizvedbenimi parametri in telesom zahteve.

Glave (Headers)

Do glav zahteve lahko dostopate z uporabo lastnosti request.headers:

            export async function GET(request: Request) {
 const userAgent = request.headers.get('user-agent');
 console.log('User Agent:', userAgent);
 return NextResponse.json({ userAgent });
}

            

              
                Copy
              
            
          

Poizvedbeni parametri (Query Parameters)

Za dostop do poizvedbenih parametrov lahko uporabite konstruktor URL:

            export async function GET(request: Request) {
 const url = new URL(request.url);
 const searchParams = new URLSearchParams(url.search);
 const id = searchParams.get('id');
 console.log('ID:', id);
 return NextResponse.json({ id });
}

            

              
                Copy
              
            
          

Telo zahteve (Request Body)

Pri zahtevah POST, PUT in PATCH lahko do telesa zahteve dostopate z uporabo metod request.json() ali request.text(), odvisno od vrste vsebine.

            export async function POST(request: Request) {
 const data = await request.json();
 console.log('Data:', data);
 return NextResponse.json({ receivedData: data });
}

            

              
                Copy
              
            
          

Vračanje odgovorov

Objekt NextResponse se uporablja za sestavljanje API odgovorov. Ponuja več metod za nastavitev glav, statusnih kod in teles odgovorov.

JSON odgovori

Za vračanje JSON odgovorov uporabite metodo NextResponse.json():

            return NextResponse.json({ message: 'Success!', data: { name: 'John Doe' } }, { status: 200 });

            

              
                Copy
              
            
          

Besedilni odgovori

Za vračanje navadnih besedilnih odgovorov uporabite konstruktor new Response():

            return new Response('Hello, world!', { status: 200, headers: { 'Content-Type': 'text/plain' } });

            

              
                Copy
              
            
          

Preusmeritve

Za preusmeritev uporabnikov na drug URL uporabite NextResponse.redirect():

            import { redirect } from 'next/navigation';
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 return NextResponse.redirect(new URL('/new-location', request.url));
}

            

              
                Copy
              
            
          

Nastavljanje glav (Headers)

Glave po meri lahko nastavite z uporabo možnosti headers v NextResponse.json() ali new Response():

            return NextResponse.json({ message: 'Success!' }, { status: 200, headers: { 'Cache-Control': 'no-cache' } });

            

              
                Copy
              
            
          

Integracija vmesne programske opreme (Middleware)

Vmesna programska oprema (middleware) vam omogoča izvajanje kode, preden vaš upravljalnik poti obravnava zahtevo. To je uporabno za avtentikacijo, avtorizacijo, beleženje in druge prečne zadeve.

Za ustvarjanje vmesne programske opreme ustvarite datoteko z imenom middleware.ts (ali middleware.js) v mapi app ali kateri koli podmapi. Vmesna programska oprema se bo uporabila za vse poti znotraj te mape in njenih podmap.

            // app/middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
 const token = request.cookies.get('auth-token');

 if (!token) {
 return NextResponse.redirect(new URL('/login', request.url));
 }

 return NextResponse.next();
}

export const config = {
 matcher: ['/protected/:path*'], // Apply this middleware to paths starting with /protected/
};

            

              
                Copy
              
            
          

Razlaga:

• Funkcija middleware preveri prisotnost avtentikacijskega žetona v piškotkih zahteve.
• Če žeton manjka, preusmeri uporabnika na stran za prijavo.
• V nasprotnem primeru dovoli, da se zahteva nadaljuje do upravljalnika poti.
• Objekt config določa, da se ta vmesna programska oprema uporabi samo za poti, ki se začnejo s /protected/.

Obravnavanje napak

Pravilno obravnavanje napak je ključno za gradnjo robustnih API-jev. Uporabite lahko bloke try...catch za obravnavo izjem in vračanje ustreznih odgovorov o napakah.

            export async function GET(request: Request) {
 try {
 // Simulate an error
 throw new Error('Something went wrong!');
 } catch (error: any) {
 console.error('Error:', error);
 return NextResponse.json({ error: error.message }, { status: 500 });
 }
}

            

              
                Copy
              
            
          

Razlaga:

• Blok try...catch prestreže vse izjeme, ki se pojavijo znotraj upravljalnika poti.
• V bloku catch se napaka zabeleži, in vrne se odgovor o napaki s statusno kodo 500 Internal Server Error.

Pretočni odgovori (Streaming Responses)

Upravljalniki poti podpirajo pretočne odgovore, kar vam omogoča postopno pošiljanje podatkov odjemalcu. To je še posebej uporabno za velike nabore podatkov ali dolgotrajne procese.

            import { Readable } from 'stream';
import { NextResponse } from 'next/server';

async function* generateData() {
 for (let i = 0; i < 10; i++) {
 await new Promise(resolve => setTimeout(resolve, 500)); // Simulate delay
 yield `Data chunk ${i}\n`;
 }
}

export async function GET(request: Request) {
 const readableStream = Readable.from(generateData());

 return new Response(readableStream, {
 headers: { 'Content-Type': 'text/plain; charset=utf-8' },
 });
}

            

              
                Copy
              
            
          

Razlaga:

• Funkcija generateData je asinhroni generator, ki z zakasnitvijo vrača dele podatkov.
• Metoda Readable.from() ustvari bralni tok iz generatorja.
• Objekt Response je ustvarjen z bralnim tokom kot telesom, glava Content-Type pa je nastavljena na text/plain.

Avtentikacija in avtorizacija

Zavarovanje vaših API končnih točk je ključnega pomena. Avtentikacijo in avtorizacijo lahko implementirate z uporabo vmesne programske opreme ali neposredno v vaših upravljalnikih poti.

Avtentikacija

Avtentikacija preverja identiteto uporabnika, ki pošilja zahtevo. Pogoste metode avtentikacije vključujejo:

• JWT (JSON Web Tokens): Generirajte žeton ob uspešni prijavi in ga preverjajte pri naslednjih zahtevah.
• Avtentikacija na podlagi sej: Uporabite piškotke za shranjevanje identifikatorjev sej in jih preverjajte pri vsaki zahtevi.
• OAuth: Delegirajte avtentikacijo na ponudnika tretjih oseb, kot sta Google ali Facebook.

Tukaj je primer JWT avtentikacije z uporabo vmesne programske opreme:

            // app/middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import jwt from 'jsonwebtoken';

const secret = process.env.JWT_SECRET || 'your-secret-key'; // Replace with a strong, randomly generated secret

export function middleware(request: NextRequest) {
 const token = request.cookies.get('auth-token')?.value;

 if (!token) {
 return NextResponse.json({ message: 'Authentication required' }, { status: 401 });
 }

 try {
 jwt.verify(token, secret);
 return NextResponse.next();
 } catch (error) {
 return NextResponse.json({ message: 'Invalid token' }, { status: 401 });
 }
}

export const config = {
 matcher: ['/api/protected/:path*'],
};

            

              
                Copy
              
            
          

Avtorizacija

Avtorizacija določa, do katerih virov lahko uporabnik dostopa. To običajno temelji na vlogah ali dovoljenjih.

Avtorizacijo lahko implementirate znotraj vaših upravljalnikov poti tako, da preverite vloge ali dovoljenja uporabnika in vrnete napako, če nima dostopa.

            // app/api/admin/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 // Assume you have a function to get the user's role from the token or session
 const userRole = await getUserRole(request);

 if (userRole !== 'admin') {
 return NextResponse.json({ message: 'Unauthorized' }, { status: 403 });
 }

 // Logic to retrieve admin data
 const adminData = { message: 'Admin data' };
 return NextResponse.json(adminData);
}

async function getUserRole(request: Request): Promise {
 // Replace with your actual logic to extract the user's role from the request
 // This could involve verifying a JWT token or checking a session
 return 'admin'; // Example: hardcoded role for demonstration
}

            

              
                Copy
              
            
          

Uvajanje upravljalnikov poti

Upravljalniki poti se uvajajo kot brezstrežniške funkcije na vašem izbranem ponudniku gostovanja. Next.js podpira različne platforme za uvajanje, vključno z Vercel, Netlify, AWS in drugimi.

Pri Vercelu je uvajanje tako preprosto kot povezovanje vašega Git repozitorija z Vercelom in potiskanje vaše kode. Vercel samodejno zazna vaš Next.js projekt in uvede vaše upravljalnike poti kot brezstrežniške funkcije.

Napredne tehnike

Robne funkcije (Edge Functions)

Upravljalnike poti je mogoče uvesti kot robne funkcije, ki se izvajajo na robu omrežja CDN, bližje vašim uporabnikom. To lahko znatno zmanjša zakasnitev in izboljša zmogljivost.

Če želite uvesti upravljalnik poti kot robno funkcijo, dodajte izvajalsko okolje edge v vašo datoteko route.ts:

            export const runtime = 'edge';

import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 return NextResponse.json({ message: 'Hello from the Edge!' });
}

            

              
                Copy
              
            
          

Strežniška dejanja (Server Actions)

Strežniška dejanja vam omogočajo izvajanje strežniške kode neposredno iz vaših React komponent. Upravljalniki poti in strežniška dejanja delujejo brezhibno skupaj, kar vam omogoča enostavno gradnjo kompleksnih aplikacij.

Tukaj je primer uporabe strežniškega dejanja za klicanje upravljalnika poti:

            // app/components/MyComponent.tsx
'use client';
import { useState } from 'react';
import { useRouter } from 'next/navigation';

async function handleSubmit(data: FormData) {
 'use server';

 const name = data.get('name');
 const email = data.get('email');

 const response = await fetch('/api/users', {
 method: 'POST',
 body: JSON.stringify({ name, email }),
 });

 if (response.ok) {
 router.refresh(); // Refresh the page to reflect the changes
 }
}

export default function MyComponent() {
 const router = useRouter();

 return (
 

 Name:
 


 Email:
 


 Create User
 
 );
}

            

              
                Copy
              
            
          

Predpomnjenje (Caching)

Predpomnjenje lahko znatno izboljša zmogljivost vaših API končnih točk. Z uporabo glave Cache-Control lahko nadzirate, kako brskalniki in omrežja CDN predpomnijo vaše odgovore.

            return NextResponse.json({ message: 'Success!' }, { status: 200, headers: { 'Cache-Control': 'public, max-age=3600' } });

            

              
                Copy
              
            
          

Ta primer nastavi glavo Cache-Control na public, max-age=3600, kar brskalnikom in omrežjem CDN sporoča, naj odgovor predpomnijo za eno uro.

Najboljše prakse

• Uporabljajte TypeScript: Izkoristite varnost tipov TypeScripta za izboljšanje kakovosti kode in preprečevanje napak.
• Validirajte zahteve: Validirajte dohodne zahteve, da zagotovite celovitost podatkov in preprečite zlonamerne vnose.
• Obravnavajte napake elegantno: Implementirajte ustrezno obravnavanje napak, da strankam zagotovite informativna sporočila o napakah.
• Zavarujte svoje končne točke: Implementirajte avtentikacijo in avtorizacijo za zaščito vaših API končnih točk.
• Uporabljajte vmesno programsko opremo: Uporabite vmesno programsko opremo za prečne zadeve, kot so avtentikacija, beleženje in validacija zahtev.
• Predpomnite odgovore: Uporabite predpomnjenje za izboljšanje zmogljivosti vaših API končnih točk.
• Nadzorujte svoje API-je: Nadzorujte svoje API-je za hitro prepoznavanje in reševanje težav.
• Dokumentirajte svoje API-je: Dokumentirajte svoje API-je, da bodo enostavni za uporabo drugim razvijalcem. Razmislite o uporabi orodij, kot sta Swagger/OpenAPI, za dokumentacijo API-jev.

Primeri iz resničnega sveta

Tukaj je nekaj primerov iz resničnega sveta, kako se lahko uporabljajo upravljalniki poti:

• API za e-trgovino: Ustvarite API končne točke za upravljanje izdelkov, naročil in uporabnikov.
• API za družbena omrežja: Ustvarite API končne točke za objavljanje tvitov, sledenje uporabnikom in pridobivanje časovnic.
• API sistema za upravljanje vsebin (CMS): Ustvarite API končne točke za upravljanje vsebine, uporabnikov in nastavitev.
• API za analitiko podatkov: Ustvarite API končne točke za zbiranje in analizo podatkov. Na primer, upravljalnik poti bi lahko prejemal podatke od sledilnih pikslov na različnih spletnih straneh in združeval informacije za poročanje.

Primer mednarodne e-trgovine: Upravljalnik poti, ki se uporablja za pridobivanje cen izdelkov glede na državo uporabnika. Končna točka bi lahko uporabila geolokacijo zahteve (pridobljeno iz IP naslova) za določitev lokacije uporabnika in vrnila cene v ustrezni valuti. To prispeva k lokalizirani nakupovalni izkušnji.

Primer globalne avtentikacije: Upravljalnik poti, ki implementira večfaktorsko avtentikacijo (MFA) za uporabnike po vsem svetu. To bi lahko vključevalo pošiljanje SMS kod ali uporabo avtentikacijskih aplikacij, ob upoštevanju predpisov o zasebnosti in telekomunikacijskih infrastruktur različnih regij.

Dostava večjezične vsebine: Upravljalnik poti, ki dostavlja vsebino v uporabnikovem želenem jeziku. To je mogoče določiti iz glave `Accept-Language` v zahtevi. Ta primer poudarja potrebo po pravilnem kodiranju UTF-8 in podpori za jezike, ki se pišejo od desne proti levi, kjer je to primerno.

Zaključek

Upravljalniki poti v Next.js zagotavljajo zmogljiv in prilagodljiv način za ustvarjanje API končnih točk neposredno v vaši aplikaciji Next.js. Z uporabo upravljalnikov poti lahko enostavno gradite robustne API-je, združujete svojo backend logiko z vašimi React komponentami in izkoriščate funkcije, kot so vmesna programska oprema, pretakanje in robne funkcije.

Ta celovit vodnik je pokril vse, od osnovne nastavitve do naprednih tehnik. Z upoštevanjem najboljših praks, opisanih v tem vodniku, lahko gradite visokokakovostne API-je, ki so varni, zmogljivi in enostavni za vzdrževanje.